home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / Kubuntu 8.10 / kubuntu-8.10-desktop-i386.iso / casper / filesystem.squashfs / usr / share / doc / pm-utils / HOWTO.hooks < prev    next >
Text File  |  2008-10-15  |  3KB  |  74 lines
  1. How to write a pm-utils hook:
  2.  
  3. PARAMETERS
  4.  
  5. A pm-utils hook is simply an executable file that accepts a single parameter.
  6. For hooks in sleep.d, the potential values of that parameter are:
  7. suspend -- The hook MUST perform whatever action is appropriate when the
  8.     system is preparing for S3 sleep (or its equivalent).
  9. suspend_hybrid -- The hook MUST perform whatever action is appropriate 
  10.           when entering suspend mode.  The hook SHOULD also save
  11.           any state it may need to bring the system back from 
  12.           hibernate mode.
  13. resume -- The hook MUST perform whatever action is appropriate when the 
  14.     system is coming out of suspend.
  15. hibernate -- The hook MUST perform whatever action is appropriate when 
  16.     the system is preparing for suspend-to-disk.
  17. thaw -- The hook MUST perform whatever action is appropriate when the system
  18.     is coming out of suspend-to-disk.
  19. help -- If your hook parses the PM_CMDLINE environment variable for switches, 
  20.     this function SHOULD output text describing the parameters it parses
  21.     in a format easily understandable by an end-user.
  22.  
  23. For hooks in power.d, the potential values of that parameter are:
  24. true -- the hook MUST perform whatever action is appropriate when the system 
  25.     transitions TO battery power.
  26. false -- The hook MUST perform whatever action is appropriate when the system
  27.     transitions FROM battery power.
  28.  
  29. NAMING SCHEME
  30.  
  31. All hooks are run in lexical sort order according to the C locale.
  32.  
  33. SLEEP.D SPECIFIC NOTES
  34.  
  35. For any given sleep/wakeup cycle, the hooks in sleep.d are run twice:
  36. * Once in C lexical sort order before the system goes to sleep, and
  37. * Once in reverse C lexical sort order when the system wakes up.
  38.  
  39. CONVENIENCE FUNCTIONS
  40.  
  41. If your hook is a shell script that supports POSIX/SuS compatible syntax, you
  42. MAY source "${PM_FUNCTIONS}". The variable will be set in the environment of
  43. the hook. This will make the following convenience functions available:
  44. 1:  try_lock
  45.     try_lock expects a single parameter -- the name of the lock to 
  46.     try to acquire.  Exit code denotes success.
  47. 2:  spin_lock
  48.     Wrapper around try_lock.  Second parameter is the number of seconds 
  49.     to wait for the lock before giving up.  If no second parameter
  50.     is passed, this function will wait forever.
  51. 3:  release_lock
  52.     Release a previously acquired lock.  First parameter is the name of the
  53.     lock.
  54. 4:  get_power_status
  55.     Outputs our power source on stdout.
  56. 5:  modunload
  57.     Unload a module.  Exit code denotes success.
  58. 6:  modreload
  59.     Reload all the modules unloaded by modunload.
  60. 7:  stopservice
  61.     Stop a service.  First parameter is the name of the service to stop.
  62. 8:  restartservice
  63.     Restart a service.  Service must have been stopped by stopservice.
  64. 9:  savestate
  65.     Save state piped into this function on stdin.  First parameter is the 
  66.     name of the state being saved.  If a second parameter is passed, this
  67.     function will use it instead of stdin.
  68. 10: restorestate
  69.     Outputs state saved by savestate on stdout.  The first parameter is the
  70.     name of the state to restore.
  71. 11: disablehook
  72.     Prevent a hook from running.  The exact name of the hook (including
  73.     numberic prefix) must be passed.
  74.